/*
 * Copyright (c) 2023 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup OHAudio
 * @{
 *
 * @brief 提供音频模块C接口定义。
 *
 * @syscap SystemCapability.Multimedia.Audio.Core
 *
 * @since 10
 * @version 1.0
 */

/**
 * @file native_audiocapturer.h
 *
 * @brief 声明输入类型的音频流相关接口。
 *
 * @library libohaudio.so
 * @syscap SystemCapability.Multimedia.Audio.Core
 * @kit AudioKit
 * @include <ohaudio/native_audiocapturer.h>
 * @since 10
 * @version 1.0
 */

#ifndef NATIVE_AUDIOCAPTURER_H
#define NATIVE_AUDIOCAPTURER_H

#include <time.h>
#include "native_audiostream_base.h"
#include "native_audio_device_base.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
 * @brief 释放输入音频流。
 *
 * @since 10
 * @permission ohos.permission.MICROPHONE
 *
 * @param capturer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @return AUDIOSTREAM_SUCCESS：函数执行成功。\n
 *         AUDIOSTREAM_ERROR_INVALID_PARAM：参数capturer为nullptr。\n
 *         AUDIOSTREAM_ERROR_ILLEGAL_STATE：执行状态异常。
 */
OH_AudioStream_Result OH_AudioCapturer_Release(OH_AudioCapturer* capturer);

/**
 * @brief 启动音频采集器，开始获取音频数据。
 *
 * @since 10
 * @permission ohos.permission.MICROPHONE
 *
 * @param capturer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @return AUDIOSTREAM_SUCCESS：函数执行成功。\n
 *         AUDIOSTREAM_ERROR_INVALID_PARAM：参数capturer为nullptr。\n
 *         AUDIOSTREAM_ERROR_ILLEGAL_STATE：执行状态异常。
 */
OH_AudioStream_Result OH_AudioCapturer_Start(OH_AudioCapturer* capturer);

/**
 * @brief 暂停输入音频流。
 *
 * @since 10
 * @permission ohos.permission.MICROPHONE
 *
 * @param capturer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @return AUDIOSTREAM_SUCCESS：函数执行成功。\n
 *         AUDIOSTREAM_ERROR_INVALID_PARAM：参数capturer为nullptr。\n
 *         AUDIOSTREAM_ERROR_ILLEGAL_STATE：执行状态异常。
 */
OH_AudioStream_Result OH_AudioCapturer_Pause(OH_AudioCapturer* capturer);

/**
 * @brief 停止音频采集器，停止输入音频流。
 *
 * @since 10
 * @permission ohos.permission.MICROPHONE
 *
 * @param capturer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @return AUDIOSTREAM_SUCCESS：函数执行成功。\n
 *         AUDIOSTREAM_ERROR_INVALID_PARAM：参数capturer为nullptr。\n
 *         AUDIOSTREAM_ERROR_ILLEGAL_STATE：执行状态异常。
 */
OH_AudioStream_Result OH_AudioCapturer_Stop(OH_AudioCapturer* capturer);

/**
 * @brief 丢弃获取的音频数据。
 *
 * @since 10
 *
 * @param capturer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @return AUDIOSTREAM_SUCCESS：函数执行成功。\n
 *         AUDIOSTREAM_ERROR_INVALID_PARAM：参数capturer为nullptr。\n
 *         AUDIOSTREAM_ERROR_ILLEGAL_STATE：执行状态异常。
 */
OH_AudioStream_Result OH_AudioCapturer_Flush(OH_AudioCapturer* capturer);

/**
 * @brief 查询当前音频流状态。
 *
 * @since 10
 *
 * @param capturer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @param state 指向一个用来接收音频流状态的变量。
 * @return AUDIOSTREAM_SUCCESS：函数执行成功。\n
 *         AUDIOSTREAM_ERROR_INVALID_PARAM：参数capturer为nullptr。
 */
OH_AudioStream_Result OH_AudioCapturer_GetCurrentState(OH_AudioCapturer* capturer, OH_AudioStream_State* state);

/**
 * @brief 查询当前音频流时延模式。
 *
 * @since 10
 *
 * @param capturer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @param latencyMode 指向一个用来接收音频流时延模式的变量。
 * @return AUDIOSTREAM_SUCCESS：函数执行成功。\n
 *         AUDIOSTREAM_ERROR_INVALID_PARAM：参数capturer为nullptr。
 */
OH_AudioStream_Result OH_AudioCapturer_GetLatencyMode(OH_AudioCapturer* capturer,
    OH_AudioStream_LatencyMode* latencyMode);

/**
 * @brief 查询当前输入音频流ID。
 *
 * @since 10
 *
 * @param capturer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @param streamId 指向一个用来接收音频流ID的变量。
 * @return AUDIOSTREAM_SUCCESS：函数执行成功。\n
 *         AUDIOSTREAM_ERROR_INVALID_PARAM：参数capturer为nullptr。
 */
OH_AudioStream_Result OH_AudioCapturer_GetStreamId(OH_AudioCapturer* capturer, uint32_t* streamId);

/**
 * @brief 查询当前输入音频流采样率。
 *
 * @since 10
 *
 * @param capturer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @param rate 指向一个用来接收音频流采样率的变量。
 * @return AUDIOSTREAM_SUCCESS：函数执行成功。\n
 *         AUDIOSTREAM_ERROR_INVALID_PARAM：参数capturer为nullptr。
 */
OH_AudioStream_Result OH_AudioCapturer_GetSamplingRate(OH_AudioCapturer* capturer, int32_t* rate);

/**
 * @brief 查询当前音频流通道数。
 *
 * @since 10
 *
 * @param capturer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @param channelCount 指向一个用来接收音频流通道数的变量。
 * @return AUDIOSTREAM_SUCCESS：函数执行成功。\n
 *         AUDIOSTREAM_ERROR_INVALID_PARAM：参数capturer为nullptr。
 */
OH_AudioStream_Result OH_AudioCapturer_GetChannelCount(OH_AudioCapturer* capturer, int32_t* channelCount);

/**
 * @brief 查询当前输入音频流采样格式。
 *
 * @since 10
 *
 * @param capturer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @param sampleFormat 指向一个用来接收音频流采样格式的变量。
 * @return AUDIOSTREAM_SUCCESS：函数执行成功。\n
 *         AUDIOSTREAM_ERROR_INVALID_PARAM：参数capturer为nullptr。
 */
OH_AudioStream_Result OH_AudioCapturer_GetSampleFormat(OH_AudioCapturer* capturer,
    OH_AudioStream_SampleFormat* sampleFormat);

/**
 * @brief 查询当前音频流编码类型。
 *
 * @since 10
 *
 * @param capturer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @param encodingType 指向一个用来接收音频流编码类型的变量。
 * @return AUDIOSTREAM_SUCCESS：函数执行成功。\n
 *         AUDIOSTREAM_ERROR_INVALID_PARAM：参数capturer为nullptr。
 */
OH_AudioStream_Result OH_AudioCapturer_GetEncodingType(OH_AudioCapturer* capturer,
    OH_AudioStream_EncodingType* encodingType);

/**
 * @brief 查询当前音频流工作场景类型。
 *
 * @since 10
 *
 * @param capturer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @param sourceType 指向一个用来接收输入类型音频流的工作场景的变量。
 * @return AUDIOSTREAM_SUCCESS：函数执行成功。\n
 *         AUDIOSTREAM_ERROR_INVALID_PARAM：参数capturer为nullptr。
 */
OH_AudioStream_Result OH_AudioCapturer_GetCapturerInfo(OH_AudioCapturer* capturer,
    OH_AudioStream_SourceType* sourceType);

/**
 * @brief 在回调中查询帧大小，它是每次回调返回的缓冲区的固定长度。
 *
 * @since 10
 *
 * @param capturer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @param frameSize 指向将为帧大小设置的变量的指针。
 * @return AUDIOSTREAM_SUCCESS：函数执行成功。\n
 *         AUDIOSTREAM_ERROR_INVALID_PARAM：参数capturer为nullptr。\n
 *         AUDIOSTREAM_ERROR_ILLEGAL_STATE：执行状态异常。
 */
OH_AudioStream_Result OH_AudioCapturer_GetFrameSizeInCallback(OH_AudioCapturer* capturer,
    int32_t* frameSize);

/**
 * @brief 获取输入音频流时间戳和当前数据帧位置信息。\n
 *
 * 该接口可以获取到音频通道实际录制位置（framePosition）以及录制到该位置时候的时间戳（timestamp），时间戳单位为纳秒。
 *
 * @since 10
 *
 * @param capturer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @param clockId 时钟标识符，使用CLOCK_MONOTONIC。
 * @param framePosition 指向要接收位置的变量的指针。
 * @param timestamp 指向接收时间戳的变量的指针。
 * @return AUDIOSTREAM_SUCCESS：函数执行成功。\n
 *         AUDIOSTREAM_ERROR_INVALID_PARAM：\n
 *                                                 1. 参数capturer为nullptr；\n
 *                                                 2. 参数clockId无效。\n
 *         AUDIOSTREAM_ERROR_ILLEGAL_STATE：执行状态异常。
 */
OH_AudioStream_Result OH_AudioCapturer_GetTimestamp(OH_AudioCapturer* capturer, clockid_t clockId,
    int64_t* framePosition, int64_t* timestamp);

/**
 * @brief 查询自创建流以来已读取的帧数。
 *
 * @since 10
 *
 * @param capturer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @param frames 指向将为帧计数设置的变量的指针。
 * @return AUDIOSTREAM_SUCCESS：函数执行成功。\n
 *         AUDIOSTREAM_ERROR_INVALID_PARAM：参数capturer为nullptr。
 */
OH_AudioStream_Result OH_AudioCapturer_GetFramesRead(OH_AudioCapturer* capturer, int64_t* frames);

/**
 * @brief 查询当前录制音频流过载数。
 *
 * @since 12
 *
 * @param capturer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @param count 指向一个用来接收音频流过载数的变量的指针。
 * @return AUDIOSTREAM_SUCCESS：函数执行成功。\n
 *         AUDIOSTREAM_ERROR_INVALID_PARAM：参数capturer为nullptr。
 */
OH_AudioStream_Result OH_AudioCapturer_GetOverflowCount(OH_AudioCapturer* capturer, uint32_t* count);

/**
 * @brief 读取音频数据的回调函数。
 *
 * @param capturer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @param userData 指向应用自定义的数据存储区域。
 * @param audioData 指向录制数据存储区域，用于应用填充录制数据。
 * @param audioDataSize 录制数据的长度。
 * @since 20
 */
typedef void (*OH_AudioCapturer_OnReadDataCallback)(OH_AudioCapturer* capturer, void* userData, void* audioData,
    int32_t audioDataSize);

/**
 * @brief 音频录制流的设备变化事件回调函数。
 *
 * @param capturer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @param userData 指向应用自定义的数据存储区域。
 * @param deviceArray 音频设备描述符数组。
 * @since 20
 */
typedef void (*OH_AudioCapturer_OnDeviceChangeCallback)(OH_AudioCapturer* capturer, void* userData,
    OH_AudioDeviceDescriptorArray* deviceArray);

/**
 * @brief 音频录制流的中断事件回调函数。
 *
 * @param capturer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @param userData 指向应用自定义的数据存储区域。
 * @param type 音频流中断类型。
 * @param hint 音频流中断提示类型。
 * @since 20
 */
typedef void (*OH_AudioCapturer_OnInterruptCallback)(OH_AudioCapturer* capturer, void* userData,
    OH_AudioInterrupt_ForceType type, OH_AudioInterrupt_Hint hint);

/**
 * @brief 音频录制流的错误事件回调函数。
 *
 * @param renderer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @param userData 指向应用自定义的数据存储区域。
 * @param error 音频流录制错误结果。
 * @since 20
 */
typedef void (*OH_AudioCapturer_OnErrorCallback)(OH_AudioCapturer* renderer, void* userData,
    OH_AudioStream_Result error);

/**
 * @brief 获取音频录制过程中的运行状态，是否在低时延状态下工作。
 *
 * @param capturer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @param status 指向接收低时延状态的指针。
 * @return AUDIOSTREAM_SUCCESS：函数执行成功。\n
 *         AUDIOSTREAM_ERROR_INVALID_PARAM：参数capturer为nullptr。\n
 *         AUDIOSTREAM_ERROR_ILLEGAL_STATE：执行状态异常，仅在释放状态之前可用。
 * @since 20
 */
OH_AudioStream_Result OH_AudioCapturer_GetFastStatus(OH_AudioCapturer* capturer,
    OH_AudioStream_FastStatus* status);

/**
 * @brief 音频录制过程中低时延状态改变事件的回调函数。
 *
 * @param capturer 指向{@link OH_AudioStreamBuilder_GenerateCapturer}创建的音频流实例。
 * @param userData 指向应用自定义的数据存储区域。
 * @param status 返回当前低时延状态。
 * @since 20
 */
typedef void (*OH_AudioCapturer_OnFastStatusChange)(
    OH_AudioCapturer* capturer,
    void* userData,
    OH_AudioStream_FastStatus status
);

#ifdef __cplusplus
}
#endif

#endif // NATIVE_AUDIOCAPTURER_H
/** @} */